Last Updated: 2023-01-16

References: FLAC 8.1 Manual: User's Guide; Command Reference; Fish in FLAC

This tutorial is aimed to help you recognize and resolve errors in your FLAC model. Sometimes the errors will be obvious, such as when the model just doesn't run, or the errors will not be as apparent. I try to point out common errors you will run into so that you don't have to spend hours troubleshooting.

This is not an exhaustive list of possible errors. If you run into something that is not included, please send it to me and I will include it in an updated version of this document.

What you'll learn

Even if your model runs, that does not mean that errors are not present. You will want to develop good modeling habits, including verification, to check that you have quality inputs to your model. Below are sections of things to think about for each model you run.

Are the assigned model properties reasonable?

The values that you select for your model properties need to be reasonable and reflect typical values. If you are unsure of reasonable values, look to resources like textbooks, manuals, or examples of published modeling projects.

Are the intended model property values assigned?

Often model property values are calculated from other input values. For example, dry density may be calculated from specific gravity and void ratio values; if the calculations are not written correctly, this would cause a bad input value.

After model properties are initialized you should pause the simulation and print the values to make sure they are correctly assigned. You can find the list of model property names by selecting Plot, Model then in the Plot Items window, expanding Properties and the model you are using. If there are bad values, check for typos and that variables are referenced consistently.

;; for example, with the Mohr-Coulomb model, you can enter the following in the command consol ;;

print bulk
print shear
print cohesion
print tension
print dilation
print friction
print state

Are the initial conditions reasonable and assigned as intended?

Just like model property values, initial values also need to be reasonable. The initial values include total stresses (sxx, syy, szz) and pore water pressure (pp). The values must represent reasonable geotechnical stress conditions, and should yield reasonable effective stress values.

After the model has been initialized and before timestepping, you should pause the simulation and print the total stresses, effective stresses and porewater pressures to make sure the values are reasonable and assigned as intended.

print sxx; print syy; print szz; print pp; print esxx; print esyy; print eszz

Are the boundary conditions correct?

The assigned boundary conditions must represent the loading conditions. Incorrect boundary conditions may lead to errors in the model or the model may run but the results will be incorrect. The latter will require your critical thinking and engineering judgment to recognize boundary condition errors. This section provides guidance if incorrect boundary conditions are preventing your model from running.

Static equilibrium

One check on your boundary conditions is whether the model quickly reaches static equilibrium. After model properties, initial conditions, and boundary conditions are assigned, but before applying loads, the model should be brought to static equilibrium. The solve command will step the model to static equilibrium.

After static equilibrium

A way to check that the loading boundary conditions are correct is to cycle through a small number of timesteps and check that the gridpoint velocities and displacements are reasonable. You can do this by pausing the scripts or commenting them out after the loading boundary conditions, and entering the step command into the console. For example:

Step 10

After those steps, check the gridpoint velocities to see that they are as expected. The example below is for a 1D compression simulation.

Sometimes FLAC tells you what the error is, sometimes you need to troubleshoot to figure out what the error is. Use the clues in the error messages to help figure out what the error is.

Compilation & Execution Errors

These are the errors where FLAC cannot execute the scripts. FLAC will stop execution when the erroneous line of script is encountered. Look in the Console for the type of error. In the example below, it is a "Command not recognized" error, meaning that there is a type in the command aptly, which should be apply.

Model run errors

If initial conditions, boundary conditions, or model properties are not properly assigned, the model will not run as intended. This may include:

These can be more difficult to identify than execution errors. For these errors you will want to look at the model velocity or displacement vectors and see if they are as expected for the condition you are trying to model. For these errors, first check that your boundary conditions and initial conditions are correct.

Below is an example of what pancaking looks like. It was caused by bad boundary conditions at the right boundary.

This part focuses on finding where the error is in the FISH scripts so the error can be corrected.

Command error

Errors may happen in a command line or in the FISH scripts. For both types of errors, it is useful to have "echo" turned on (echo on). The echo command reads out the called file and the scripted commands into the console and gives the error when the erroneous command line is encountered.

In the GUI console, look at where the model stopped running. In the example below, the error occurs from a typo in the history parameter assignment (should be unbal not unbalo). From looking at the console, you can see that the FLAC could not run that command line and therefore stopped running.

Fish Compilation or Execution Error

Fish compilation errors happen within FLAC's user defined language. As opposed to command errors, the model will not necessarily stop reading out at the erroneous line. This means that you may have to do some digging to find the error line.

The model often will not run if:

Example of locating a divide by zero error

This is often the shortest step; usually figuring out what and where the error is takes the most time. This step is usually just fixing a typo, saving the file, and then re-running the model (and maybe running into the next error).

If you are having trouble saving the .fis file, see the Common Errors section.

Often .fis files cannot be saved when they are edited after running into a FLAC error. In Notepad++ the error will look like this:

This happens because the file is still open in FLAC - FLAC didn't finish running through the file because it ran into the error. To save the changes to the .fis file, you will need to tell FLAC to start a new model: type "new" in the FLAC command line and press enter.

You should now be able to call the .fis model from FLAC.

This error will occur as the model is timestepping. A "zero or negative density in one or more zones" message will occur in the console. A "communication thread exception" message may come up as well.

Where is the bad density value?

You can track down which zone is the problem by using the print command with density. This can be useful to understand what caused the error. In the example below, the problem zone is i=2 j=1.

print density

When did the error occur?

When the error occurs gives a hint of what caused the error.

What are the bad density values?

The erroneous density values provide a clue to why the value is bad.